Memòria EntreBicis Héctor

Nom: Héctor Vico
Any: 2025
Curs: DAM2M
Equip docent: Manel Orós, Esther Sánchez, Jordi Cárdenas

Recollida Requisits

Contextualització de l’organització client

L’organització que ha sol·licitat aquest projecte és Aprop Garraf, una entitat compromesa amb la mobilitat sostenible i el foment de l’ús de la bicicleta com a mitjà de transport ecològic i accessible. L’organització busca incentivar l’ús responsable de les bicicletes mitjançant la creació d’una aplicació que permeti registrar rutes i recompensar els ciclistes per la distància recorreguda.

Objectius de l’organització

Aprop Garraf té com a finalitat principal promoure la mobilitat sostenible i incentivar el transport actiu dins la comunitat. Els objectius específics de l’entitat són:

Fomentar l’ús de la bicicleta per reduir la dependència dels vehicles motoritzats.
Premiar els usuaris actius a través d’un sistema de punts bescanviables per productes o serveis locals.
Crear una comunitat de ciclistes que participin activament en la iniciativa.
Recolzar el comerç local, promovent la col·laboració amb establiments que ofereixin recompenses als ciclistes.
Garantir un registre fiable de rutes, que permeti validar l’activitat dels usuaris de manera transparent i segura.

A través d’aquesta aplicació, Aprop Garraf busca combinar la tecnologia amb la sostenibilitat, creant un entorn en què la mobilitat neta sigui atractiva i accessible per a tothom.

Breu resum del projecte

Aquest projecte té com a objectiu el desenvolupament d’un sistema digital compost per una aplicació mòbil per als usuaris ciclistes i una plataforma web per a l’administrador. La iniciativa és impulsada per Aprop Garraf amb l’objectiu de fomentar la mobilitat sostenible mitjançant un sistema de recompenses per als ciclistes.

Estructura del sistema

Aplicació mòbil per a Android: Utilitzada pels ciclistes per registrar les seves rutes, acumular punts en funció dels quilòmetres recorreguts i bescanviar-los per recompenses en establiments col·laboradors.
Plataforma web per a l’administrador: Serveix per gestionar els usuaris, validar les rutes i controlar el sistema de punts i recompenses.

Funcionalitats principals

Registre i validació d’usuaris: L’usuari s’haurà de registrar a l’aplicació i l’administrador validarà manualment cada compte des de la plataforma web.
Seguiment de rutes mitjançant geolocalització: L’app mòbil registrarà els trajectes dels ciclistes en temps real.
Càlcul i acumulació de punts: Els punts s’assignaran segons la distància recorreguda i es podran bescanviar per recompenses.
Sistema de recompenses en establiments locals: Els usuaris podran utilitzar els punts acumulats per obtenir productes o serveis en comerços col·laboradors.
Gestió centralitzada des de la plataforma web: L’administrador podrà validar rutes, aprovar registres d’usuaris i gestionar el catàleg de recompenses.

Els requeriments funcionals i no funcionals

Requeriments funcionals (RF)

Els requeriments funcionals i no funcionals

Requeriments funcionals (RF)

Els requeriments funcionals indiquen les accions que ha de permetre fer l’aplicació per als diferents usuaris (ciclista i administrador).

RF01: Validar ruta → L’administrador revisa una ruta i la valida si compleix els criteris establerts. La ruta es troba prèviament no validada i quan es valida la ruta s’afegeix el saldo al compte de l’usuari.
RF02: Invalidar ruta → Si una ruta no compleix els requisits, l’administrador pot invalidar-la.
RF03: Iniciar ruta → L’usuari pot començar una nova ruta manualment des de l’aplicació mòbil, sempre que no tingui cap altra ruta en curs.
- S’haurà de consultar el paràmetre de sistema Temps màxim d’aturada per si s’ha de considerar que s’ha de finalitzar la ruta de manera automàtica.
RF04: Visualitzar detalls ampliats d’una ruta → El sistema ha de permetre a l’usuari ciclista consultar la informació detallada de les rutes que ha realitzat. Aquesta informació ha de ser mostrada de manera clara i precisa, incloent:
- Distància recorreguda: Mostrada amb precisió de metres, des del punt inicial fins al punt final de la ruta.
- Temps total de la ruta: El temps complet des que la ruta va començar fins que es va finalitzar.
- Velocitat màxima: La velocitat més alta registrada durant la ruta.
- Velocitat mitjana: Calculada com la distància recorreguda dividida pel temps total.
- Mapa interactiu: Visualització de tots els punts recorreguts sobre un mapa, connectats per línies.
  - El mapa ha de permetre funcionalitats de zoom i desplaçament lateral per una millor visualització.
  - En fer clic sobre qualsevol punt del recorregut, es mostrarà la seva informació de latitud i longitud.
- Aquesta funcionalitat serà accessible només per a l’usuari ciclista per les seves pròpies rutes. L’administrador, en canvi, tindrà accés per visualitzar qualsevol ruta independentment de l’usuari que l’hagi realitzat.
RF05: Finalitzar ruta → Un cop acabada la ruta, l’usuari pot finalitzar-la manualment perquè sigui processada.
- Només es podrà finalitzar la ruta que es trobi en estat "en curs".
- Un cop finalitzada, ja no es podran afegir més punts a la ruta.
- Un cop finalitzada, la ruta quedarà per defecte en estat "no validada" i haurà d’esperar l’aprovació de l’administrador per passar a "validada".
- Un cop finalitzada, l’usuari visualitzarà els detalls de la ruta, seguint la funcionalitat descrita en RF Visualitzar detalls d’una ruta o Visualitzar detalls ampliats d’una ruta.
RF06: Llistar rutes → L’usuari pot veure un llistat de les seves rutes anteriors amb informació bàsica.
- La velocitat mitjana es calcula com la distància recorreguda dividida pel temps total.
RF09: Crear recompensa → El sistema ha de permetre crear una nova recompensa i assignar-la a un punt de bescanvi.
- El punt de bescanvi serà un string amb el nom del negoci i l’adreça.
RF11: Eliminar recompensa disponible → L’administrador pot suprimir recompenses que no estiguin reservades o assignades.
RF12: Reservar recompensa → L’usuari pot reservar una recompensa si té suficients punts disponibles.
- Saldo suficient: El valor unitari de la recompensa no pot superar el saldo disponible de l’usuari en el moment de la reserva.
- Reserva única: Un usuari només pot tenir una recompensa reservada al mateix temps. Fins que aquesta no sigui recollida o desassignada, no podrà reservar-ne cap altra.
- Disponibilitat de la recompensa: No es podrà fer una reserva si la recompensa ja està assignada, reservada o recollida per un altre usuari.
RF14: Assignar recompensa → Un cop l’usuari ha reservat una recompensa, l’administrador ha d’assignar-la abans que pugui ser recollida.
RF16: Recollir recompensa → Un cop reservada, l’usuari ha d’anar a la botiga i mostrar la seva reserva per obtenir la recompensa.
- Consultar la recompensa assignada: L’usuari podrà veure la recompensa que té assignada, incloent el nom del punt de bescanvi i la descripció de la recompensa.
- Mostrar la informació de la recompensa al punt de bescanvi: Quan l’usuari arribi al punt de recollida, podrà visualitzar en el seu dispositiu el nom del punt de bescanvi i el nom de la recompensa de manera destacada i clara.
- Confirmació de la recollida: Un cop el ciclista hagi rebut la recompensa, haurà de fer clic en un botó anomenat "Entregat". En fer-ho, apareixerà una imatge gran en el dispositiu del ciclista amb la paraula "ENTREGAT" de manera visible i clara.
- Marcar la recompensa com a recollida: Després de la confirmació, la recompensa es marcarà com a "recollida" al sistema. Es guardarà la data i hora de la recollida, i es bloquejaran qualsevol altre tipus de modificació sobre aquesta recompensa.
RF18: Llistar recompenses → El sistema ha de permetre llistar les recompenses mostrant les següents dades per cada recompensa:
- Nom de la recompensa
- Punt de bescanvi
- Punts associats a la recompensa
- Estat de la recompensa (disponible, reservada, assignada, recollida)
- Nom de l’usuari (només en el cas que estigui reservada, assignada o recollida)

Condicions d’accés:
Ciclista: Només pot veure les recompenses disponibles o les seves pròpies recompenses (reservades, assignades o recollides).
Administrador: Pot veure el llistat complet de totes les recompenses, independentment de l’estat de cada una.

RF21: Mostrar detall de la recompensa → El sistema ha de permetre consultar les característiques d’una recompensa seleccionada dins el llistat de recompenses (segons RF18), mostrant els següents detalls:
- Nom de la recompensa
- Nom complet de l’usuari (només en el cas que sigui una recompensa reservada, assignada o recollida per un ciclista)
- Nom del punt de bescanvi
- Adreça del punt de bescanvi
- Estat de la recompensa (disponible, reservada, assignada o recollida)
RF22: Crear usuari → L’administrador pot donar d’alta nous usuaris després de la seva validació manual.
RF23: Modificar usuari → L’administrador pot modificar les dades d’un usuari existent.
- Els usuaris ciclistes que no són administradors tan sols poden modificar el seu perfil.
RF25: Llistar usuaris → Es pot veure una llista d’usuaris registrats al sistema amb la següent informació:
- Nom complet de l’usuari
- Correu electrònic de l’usuari
- Estat de l’usuari (actiu o desactivat)
- Rol de l’usuari (ciclista, admin)
RF26: Visualitzar detalls de l’usuari → L’administrador pot accedir a la informació completa d’un usuari concret:
- Foto de l’usuari (si en té)
- Nom complet
- Correu electrònic
- Estat actual (actiu o desactivat)
- Rol (ciclista, admin)
- Saldo disponible (validat)
- Historial de rutes: Una llista amb totes les rutes que l’usuari ha realitzat, amb el seu estat actual (no validada, validada) i els punts de saldo associats.
- Historial de recompenses: Detalls de les recompenses que l’usuari ha reservat, assignat, recollit amb l’estat de cadascuna.
- En el cas de l’usuari ciclista, només podrà visualitzar les dades del seu perfil.
RF27: Recuperar password usuari → El sistema ha de permetre que qualsevol usuari, tant administrador com ciclista, pugui recuperar el password en cas d’haver-lo oblidat d’una manera segura.
RF29: Login / Logout → Els usuaris han de poder iniciar i tancar sessió de manera segura.
- Usuari Ciclista:
  - Login: El ciclista ha de poder fer login a l’app mòbil utilitzant el seu correu electrònic i contrasenya.
  - Logout: El ciclista ha de poder sortir de la seva sessió de l’app mòbil en qualsevol moment.
- Usuari Administrador:
  - Login: L’administrador ha de poder fer login tant a l’app mòbil com al frontend web utilitzant el seu correu electrònic i contrasenya.
  - Logout: L’administrador també ha de poder sortir de la seva sessió tant a l’app mòbil com al frontend web en qualsevol moment.
RF36: Modificar paràmetres del sistema → L’administrador pot modificar aspectes generals del sistema:
- Velocitat màxima vàlida: Determina la velocitat màxima permesa per registrar una ruta correctament. Per defecte, 60 km/h.
- Temps màxim d’aturada: Temps màxim que un usuari pot estar aturat abans que la ruta es finalitzi automàticament. Per defecte, 5 minuts.
- Conversió entre saldo i quilòmetres: Defineix la relació entre la distància recorreguda i els punts acumulats. Per defecte, 1 km = 1 punt.
- Temps màxim per recollir la recompensa: Període màxim per recollir una recompensa assignada al punt de bescanvi. Per defecte, 72 hores.

Requeriments no funcionals (RNF)

Requeriments generals

RN01: L’aplicació ha de permetre fins a 50 usuaris actius.
RN02: L’arquitectura ha de ser client-servidor, amb API REST en Spring Boot.
RN03: El sistema ha de tenir un registre de logs per detectar errors i incidències.
RN04: El codi ha de ser eficient i sense redundàncies, seguint bones pràctiques de desenvolupament.
RN05: L’estructura del codi ha de seguir patrons d’arquitectura adequats per a cada tecnologia utilitzada.
RN06: Les classes i mètodes han d’estar documentats amb JavaDoc per al backend i KDoc per al codi Kotlin.
RN07: Qualsevol excepció que es produeix durant l’execució ha de ser degudament informada a l’usuari amb informació concreta i comprensible.
RN09: S’ha d’utilitzar git/gitlab per implementar el projecte de forma òptima.
RN12: La comunicació entre el frontend mòbil i el backend s’ha de portar a terme mitjançant els principis REST.

Requeriments del frontend mòbil (aplicació)

RN20: L’app s’ha de desenvolupar amb Android Studio i el llenguatge Kotlin.
RN21: Ha de seguir l’arquitectura Feature Layer i Clean Architecture.
RN22: Ha de seguir el patró MVVM per separar la lògica de negoci i la interfície d’usuari.
RN23: La interfície gràfica s’ha d’implementar amb Jetpack Compose.
RN24: Ha de seguir les directrius de Material Design.

Requeriments del backend

RN41: L’estructura del projecte ha de ser de tipus Maven.
RN42: Les capes de servei, lògica de negoci i de persistència han d’estar ubicades al backend.
RN43: El backend s’ha d’implementar mitjançant Spring Boot.

Requeriments del frontend web

RN51: L’usuari administrador ha de poder accedir a l’aplicació mitjançant un navegador web.
RN52: Ha de ser responsive i accessible.
RN53: La interfície ha de ser intuïtiva i eficient.

Seguretat

RN61: Ha d’incloure autenticació amb usuari i contrasenya.
RN63: Les contrasenyes han d’estar xifrades mitjançant tècniques de hash robustes.
RN64: La informació personal dels usuaris ha d’estar protegida en tot moment.

Desplegament (deploy)

RN71: El backend i la base de dades han d’estar allotjats al mateix servidor.
RN72: El desplegament s’ha de poder realitzar mitjançant contenidors Docker.

Guions per actors

Actor: Ciclista (Usuari de l’App Mòbil)

RF03: Iniciar ruta → L’usuari pot començar una nova ruta manualment des de l’aplicació mòbil, sempre que no tingui cap altra ruta en curs.
RF04: Visualitzar detalls ampliats d’una ruta → L’usuari pot consultar la informació detallada de les seves rutes, incloent distància, temps, velocitat i visualització en mapa interactiu.
RF05: Finalitzar ruta → L’usuari pot finalitzar la seva ruta manualment perquè sigui processada.
RF06: Llistar rutes → L’usuari pot veure un llistat de les seves rutes anteriors amb informació bàsica.
RF12: Reservar recompensa → L’usuari pot reservar una recompensa si té suficients punts disponibles.
RF16: Recollir recompensa → L’usuari ha d’anar a la botiga i mostrar la seva reserva per obtenir la recompensa.
RF18: Llistar recompenses → Els usuaris podran veure un llistat de totes les recompenses disponibles i el seu estat.
RF21: Mostrar detall de la recompensa → Mostra les característiques d’una recompensa seleccionada dins el llistat de recompenses.
RF23: Modificar usuari → L’usuari tan sols podrà modificar les seves dades d’usuari.
RF26: Visualitzar detalls de l’usuari → L’usuari podrà veure les seves dades d’usuari, és a dir, el seu perfil.
RF27: Recuperar password usuari → L’usuari pot sol·licitar la recuperació de la seva contrasenya en cas d’oblit.
RF29: Login / Logout → L’usuari pot iniciar sessió i tancar-la a l’aplicació mòbil.

Actor: Administrador (Usuari de la Plataforma Web)

RF01: Validar ruta → L’administrador revisa una ruta i la valida si compleix els criteris establerts, afegint els punts corresponents a l’usuari.
RF02: Invalidar ruta → Si una ruta no compleix els requisits, l’administrador pot invalidar-la.
RF03: Iniciar ruta → L’usuari pot començar una nova ruta manualment des de l’aplicació mòbil, sempre que no tingui cap altra ruta en curs.
RF04: Visualitzar detalls ampliats d’una ruta → L’usuari pot consultar la informació detallada de les seves rutes, incloent distància, temps, velocitat i visualització en mapa interactiu.
RF05: Finalitzar ruta → L’usuari pot finalitzar la seva ruta manualment perquè sigui processada.
RF06: Llistar rutes → L’usuari pot veure un llistat de les seves rutes anteriors amb informació bàsica.
RF09: Crear recompensa → L’administrador pot crear una nova recompensa i assignar-la a un punt de bescanvi.
RF11: Eliminar recompensa disponible → L’administrador pot suprimir recompenses que no estiguin reservades o assignades.
RF12: Reservar recompensa → L’usuari pot reservar una recompensa si té suficients punts disponibles.
RF14: Assignar recompensa → Un cop l’usuari ha reservat una recompensa, l’administrador ha d’assignar-la abans que pugui ser recollida.
RF16: Recollir recompensa → L’usuari ha d’anar a la botiga i mostrar la seva reserva per obtenir la recompensa.
RF18: Llistar recompenses → L’administrador pot veure un llistat de totes les recompenses disponibles i el seu estat.
RF21: Mostrar detall de la recompensa → L’administrador pot consultar les característiques d’una recompensa seleccionada.
RF22: Crear usuari → L’administrador pot donar d’alta nous usuaris després d’una validació manual.
RF23: Modificar usuari → L’administrador pot modificar les dades d’un usuari existent.
RF25: Llistar usuaris → L’administrador pot veure una llista d’usuaris registrats.
RF26: Visualitzar detalls de l’usuari → L’administrador pot accedir a la informació completa d’un usuari.
RF27: Recuperar password usuari → L’administrador pot generar un procés segur de recuperació de contrasenya per als usuaris.
RF29: Login / Logout → L’administrador pot iniciar sessió tant a l’aplicació mòbil com a la plataforma web.
RF36: Modificar paràmetres del sistema → L’administrador pot modificar aspectes generals com la velocitat màxima permesa o el temps màxim d’aturada.

Actor: Sistema (Processos Automàtics)

RF05: Finalitzar ruta → Quan un usuari finalitza una ruta, el sistema la deixa en estat "no validada" i espera la validació de l’administrador.